Amiga ISO Collection/AmigaMiscModsCD3.iso/_PROGRAMME/PLAYER/SINGLEFORMAT/RTracker.lzh/RTracker/RTracker Docs/RTracker_V2.0.Doc

Text File | 1992-09-26 | 45.9 KB | 1,220 lines

Contents

Copyright

Preface

1  Installation
    1.1  The Install Program
2  Introduction
3  The Interface
    3.1  The Script Files
        3.1.1  RTLoad.script
        3.1.2  RTQuit.script
        3.1.3  RTPrefs
        3.1.4  Decompress.RTPrefs
    3.2  The Main Window
        3.2.1  Gadgets
            3.2.1.1  Control Panel
            3.2.1.2  Misc. Panel
            3.2.1.3  Position Panel
            3.2.1.4  Volume Panel
            3.2.1.5  Tempo Panel
        3.2.2  Menus
            3.2.2.1  Project Menu
            3.2.2.2  Settings Menu
            3.2.2.3  Control Menu
    3.3  The Prefs Window
        3.3.1  Gadgets
            3.3.1.1  Defaults Panel
            3.3.1.2  F/X Panel
            3.3.1.3  Timing Panel
            3.3.1.4  Bootup Panel
            3.3.1.5  Default MOD Path Panel
            3.3.1.6  Port Panel
            3.3.1.7  Confirm Panel
        3.3.2  Menus
    3.4  The About Window
        3.4.1  Gadgets
        3.4.2  Menus
    3.5  AREXX Commands
4  The Player
    4.1  AREXX Commands
5  The Libraries
    5.1  DESTracker
    5.2  RexxHost
6  Credits
7  The Future
8  Index
9  Disclaimer

Copyrights

RTracker 2.0 and RTInterface 2.0 are Copyright (c) 1991, 1992 Mike R.
Manzano, All Rights Reserved.

DESTracker.Library is Copyright (c) 1992 Darren Schebek, All Rights
Reserved.

RexxHost.Library was created and put in the Public Domain by Olaf Barthel.

RTracker and RTInterface is SHAREWARE.  This archive is freely
distributable.  If you use this program often, please send 7 American
dollars (or the equivalent in your local currency) to:

Mike R. Manzano
RT/Basic
10949 Hillsboro Dr. NW
Silverdale, WA  98383

Registered users will receive a hard copy version of the manual, and a full
release disk.  Registered users will also receive other RTracker modules (a
Scope program with configurable VU meters, and a spectrum analyzer; a
multi-module selector, with options for programmed or random play, etc.) on
the same disk, and will receive notification upon the release of new
module.

I realize that by putting this program out as ShareWare, I will receive a
lot less than if I had put it out commercially, but I wanted to make it
affordable for everyone to use without going through a lot of hassle.  I
did not just put an arbitrary price on this software; I asked many people
for their opinion on what the software is worth, and used the most common
answer.  So now I am BEGGING you on my hands and knees to register this
software.  I'm going through college right now, and could always use the
money.

Preface

For quite a while, I have been looking for the perfect MOD player to suit
all my needs.  It had to be small, easy to use, highly configurable, and
invisible.  By invisible, I mean that the user shouldn't have to think when
operating the interface; it should be obvious what everything does.  Ed
Mackey's EDPlayer has come (by far) the closest to perfection.

However, two of the most annoying aspects to using a MOD player are the
lack of configurability, and the sometimes very flashy, un-standard
interfaces.  My answer to these problems (and others) is RTracker.

Because of RTracker's modular architecture, it can be easily configured to
meet the end user's needs, giving you the power to create your own
"perfect" MOD Player.  RTracker was not written with just my needs in mind,
but with everyone's needs in mind.  That's one of the reasons that RTracker
has already gone through multiple revisions.

RTracker's interface, RTInterface, has the look and feel of a normal
AmigaDOS program, and attempts to use all standards set by Commodore's
style guide.  The interface is just that - an interface.  There aren't any
fancy VU meters, spectrum analyzers, counters, and so forth.  That's left
to another program to do.  It supports automatic decompression of MODs,
which saves disk space, and eliminates the need to manually decompress
MODs.

RTracker itself is only a window; you can't control it from anything but
AREXX.  This is perfect for those users who would like to play MODs in
their multimedia presentations, but don't want their memory and processor
taken up by snazzy, but otherwise useless graphics.

Also, because RTracker uses a shared library to play it's MODs, one simply
has to replace the library with newer versions to take advantage of newer
MOD formats.

RTracker, RTInterface, and other RTracker modules are the product of many
people's ideas, recommendations, and ideals.  I hope you enjoy the result.
If you have an idea that would make RTracker easier to user, feel free to
write me at my address above.  I'll do my best to incorporate them into a
future revision.

Now, you might be asking yourself, "why all this for a MOD program?  Why
not do this with something really useful, like a paint program, or a Word
Processor?"  Well, that's because of several facts.  First, it would take
much more time than I have to program something large like that.  Second, I
am 100% certifiably insane and suffer from chronic bouts of delusions of
gradeur.  Ahahahahah!!!  MOD Players are my life!!!  Ahahahaha!!!  I am a
MOD Player!!!  Ahahahahaha!  Um, anyway, on with the program.

1  Installation

Section 1 describes how to install the RTracker distribution, and make it
executable.  RTracker will not function correctly until properly installed.

WARNING:  Running the program without installation may be hazardous to your
health.  Please make sure you install it properly before running.


1.1  The Install Program

The installation program used is Commodore's standard Installer program, so
the process should be familiar to those of you that have used it before.
The prompts and help function should be self explanatory.

The installer will do the following modifications to your system disk (not
in any order):

*  It will create a directory with the name and location of your choice.
*  RTracker and various support files will be copied into that directory.
*  The assign "PREFS:" will be added to the s:User-Startup.
*  The libraries Destracker.library and RexxHost.library will be copied to
your LIBS: directory if (1) they don't yet exist there, or (2) the version
already installed there is an older version.
*  Depending on if and where you have certain file de-crunchers, the
installer will automatically configure RTInterface to use those
de-crunchers.  At this point, the installer will attempt to modify the
Decompress.RTPrefs file for LHa compression, and PowerPacker compression.
*  The installer will ask you for your default MOD directory, and modify
RTPrefs to use that.
*  You will be prompted to create a new directory where all decompression
will take place.  See section 1.2.4.


2  Introduction

Welcome to RTracker, the first user configuable, modular, standard 2.0ish,
and otherwise easy-to-use MOD player.

First, what exactly is a MOD?  MOD, which is the short form of MODULE, is a
music file format that was created to make programming music for games and
demos easier and less time consuming.  There are a multitude of programs
that will output this format.  The four major ones are SoundTracker,
NoiseTracker, StarTrekker, and ProTracker.  The programs, or Trackers, as
they are called, are music sequencers.  Because of the quality of sound of
these musical compositions, people have started to listen to them
separately from the games and demos, and even started creating their own
just to listen to.  The popularity of MODs has become so great that the
standard Amiga song format, SMUS, is possibly no longer the most
widely-used format.

Of course, you can't listen to MODs unless you have a program to play them.
Since then, people have created many different MOD players; but none of
them really attempted to be completely system compatible and standardized
(with the possible exception of Multiplayer, which I haven't yet seen).

With the introduction of the 2.0x operating system, standardization became
a significant subject.  RTracker attempts to follow those standards while
being flexible enough that the users can customize it.

RTracker is the result of many people's ideas of how a MOD player should
operate.  Among it's many features are:

*  Default MOD path selection, so MODs can be accessed easily.
*  Automatic decompression of multiple compression formats.  Automatic
decompression can be set up to use any compression programs that you own or
use.
*  A modular architecture.  You need not take up precious memory with
options and gauges that serve no function to you.
*  A standard 2.0 interface, and full compatibility with 2.0x.  It haseven been tested on 2.1 and 3.0x systems.
*  Full AREXX support.  In fact, the main communications protocol used when
the modules interact is AREXX.
*  Full configurability.  I tried not to assume anything when creating the
player.
*  Program support.  I promise to put out timely upgrades, and will attempt
to integrate your ideas with the system.

How exactly does RTracker work?  Two modules make up the RTracker basic
program - the RTracker player, and an RTracker external module named
RTInterface.

RTracker is simply a window with an AREXX port, and nothing else.  It is
the heart of all the collective modules, although it as well can be
replaced.

RTInterface is where the average user can take advantage of RTracker's
features.  Because RTInterface can automatically load and unload RTracker
and other modules, you can consider RTracker and all its external modules
as one program.

This manual will describe in-depth how RTracker and its modules work
together.


3  The Interface

RTInterface is a GUI (Graphics User Interface) specifically designed to
communicate and command the player in a logical and easy to use manner.
Although the interface doesn't take full advantage of all the features in
the player module, the range of functions it has is more than enough for an
average user.



3.1  The Script Files

RTInterface uses four different script files to function properly, two of
which are created at install time.  All script files are easily editable
with a standard text editor.  RTLoad.script is a standard script file that
RTInterface executes on bootup.  RTQuit.script is a standard script file
that RTInterface executes upon shutdown.  RTPrefs is a self-documented
ASCII file that describe's RTInterface's preference settings.
Decompress.RTPrefs describes your external compression formats.


3.1.1  RTLoad.script

RTLoad.script is an AmigaDOS script file that RTInterface will execute upon
bootup.  These programs can be anything you want, but typically, you'll
want to run RTracker Modules here.  The current script is as follows:

.key path

; RTInterface script to autoload some modules
; path is the current default path in RTPrefs.

; WARNING:  Make sure you handle all cases where the file name has
;           a space in it!  (Such as "The File Name").  Either don't
;           use spaces in your file name, or use quotes.

; Load RTracker
  "<path>RTracker"

When the script is run, the current RTracker passes the current RTracker
path (the path where all RTracker modules exists, along with all the
support files, except for possibly RTPrefs) to the variable "path" in the
script file.  Comments are specified by
including a semi-colon before the comment.  As you can see, only one
command is executed:

"<path>RTracker"
This command runs RTracker from the current path.  The "path" variable
always ends with the proper terminating character - either a colon, or a
slash - so you shouldn't include one in your command.  Also, notice that
quotes encase the command.  This provides for the possibility that the path
name contains spaces.  As you may already know, AmigaDOS requires that
there not be any spaces in a file name unless quotation marks surround the
file name.

Another thing to keep in mind is that RTInterface will not continue until
the script file has finished executing.  Make sure the commands that you
put in here either release the CLI, or incorporate redirection to NIL:.  As
an example of the latter, say you have a program called LScope, and that
LScope doesn't release the CLI on bootup.  The entry for LScope would be:

"<path>LScope >NIL: <NIL:"

If LScope has parameters, the format would be:

"<path>LScope >NIL: <NIL: <param1> <param2> <param3> ..."

Of course, it is always safe to redirect whether the program releases the
CLI or not.  If you are unsure of whether or not a program releases the
CLI, redirect to NIL:.


3.1.2  RTQuit.script

RTQuit.script is similar to RTLoad.script in that it is also an AmigaDOS
script file.  Therefore, if follows that RTQuit.script follows all the same
rules as RTLoad.script.  Please read the RTLoad.script section (3.1.1) for
auxiliary uses of RTQuit.script.

The main use of RTQuit.script is to tell the programs that were previously
loaded with RTLoad.script to quit.  This implies that the programs you run
must be terminable externally from the CLI.  Otherwise, the user must
manually click on an close gadget to get rid of it.  The current
RTQuit.script is as follows:

.key path

; RTInterface script to unload programs
; path is the default path (usually where programs are)

; WARNING:  Make sure you handle all cases where the file name has
;           a space in it!  (Such as "The File Name").  Either don't
;           use spaces in your file name, or use quotes.


; Unload RTracker
  rx "address 'RTracker';quit"

As you can see, the only command executed is:

rx "address 'RTracker';quit"

This runs the program rx (the AREXX interpreter), tells it to talk to the
port 'RTracker' (which is RTracker's AREXX port), and then gives RTracker
the command to quit.  It is important to note that if you don't put quotes
around the port name, AREXX will
automatically capitalize the name, and the port name is case sensitive.
Putting quotes is always a good idea.

The command to quit from your own program is up to you; this manual can't
possibly document all possible programs, and their methods of quitting.
Refer to your program's manual for further instruction.


3.1.3  RTPrefs

RTPrefs is the main preferences file for RTInterface.  It is a plain ASCII
text file that describes how RTInterface should act.  An example RTPrefsfollows:

128 Auto Play
128 Decompress
0 Auto Detect PAL/NTSC
128 Request on Eject
0 NTSC/PAL default switch; NTSC = 0, PAL = 1
0 Filter on/off
128 Repeat at end
128 Auto Load Rtracker player program on bootup
128 Auto Unload RTracker player program on shutdown
128 Request on Bootup
Work:RTracker
Tracks:
Unused

A left-aligned number field followed by an optional comment compose all the
entried except for the last three.  A number other than zero specifies that
the option is ON, and a zero specifies that the option is OFF.  The last
three fields are strings; the first two are path names, and the last is
unused.

The first entry, Auto Play, tells RTInterface whether or not to start
playing the MOD once you load it, regardless to if you clicked on the PLAY
gadget.

The Decompress entry will disable/enable automatic decompression.  See
section 3.1.4 for more information about this topic.

Auto Detect PAL/NTSC tells RTInterface to automatically determine the
correct timing for a MOD.  This will only work for MODs with the special
DesTracker timing information imbedded in the MOD.  Registered users will
receive this program when completed.  Unless you have this program, or a
program that will save it in this format for you, such as Darren Schebek's
DTC program, it is a good idea to disable this option.

Request on Eject specifies if RTInterface should request you for another
file name when you eject the currently loaded MOD.

The NTSC/PAL default switch only takes effect if Auto Detect PAL/NTSC is
deactivated.  Upon bootup, and upon loading a new MOD, RTracker examines
this entry to see what timing the MOD should use.

Filter ON/OFF specifies whether or not the filter should activat upon
loading a new MOD into memory.

Repeat at end will tell RTInterface whether to loop back to the beginning
of the song when the current play sequence completes.  If disabled, the
player will stop playing at the end of the song.

Auto Load specifies whether or not RTInterface should execute the
RTLoad.script file upon start up.

Auto UnLoad specifies if RTInterface should execute RTQuit.script upon
shutdown.

Request on Bootup specifies if RTInterface should request you for a file
name immediately after the bootup sequence finishes.

The first string entry, the RTracker path (the one that says Work:RTracker
in the example), specifies the storage location of the support files (all
the scripts bar this one), RTracker, and RTracker modules.  It is the path
name that RTracker passes to the <path> variable in the RTLoad.script and
RTQuit.script script files.  See sections 3.1.1 and 3.1.2 for more
information.

The second string entry, the default MOD path, is the path that RTInterface
will automatically lock on to when presenting you with a file requester.

The third string field is, as of yet, unused.  Ignore this field, but leave
it there.Please note that there should be no comments on the entries that contain
strings.


3.1.4  Decompress.RTPrefs

Out of all the script files, the Decompress.RTPrefs script is the most
cryptic, but you'll find after looking at it closely, it isn't cryptic
after all.  When you installed RTracker, the installer created
Decompress.RTPrefs for you, with up to two entries.  These entries (one per
line) describe to RTInterface how it should handle decompressing certain
files.  The two that may have been installed are LHa, and PowerPacker's
Decrunch utility.  The file is in this format:

<pattern>|<command>|<decompress dir>|
<pattern>|<command>|<decompress dir>|
<pattern>|<command>|<decompress dir>|
...
@

If you did not have both LHa and Decrunch, or chose not to install them,
the file should contain only the at-sign (@).  The at-sign tells
RTInterface that it has reached the end of the file.

The best way to illustrate it's use is to give an example.  Take the
following example Decompress.RTPrefs:

#?.LHA|c:lha >con:0/0/500/100/Decompressing e "%"
Work:RTracker/|Work:RTracker|
#?.pp|c:decrunch >con:0/0/500/100/Decompressing "%"
Work:RTracker|Work:RTracker|
@

Take note that each entry must exist on one, and only one, line.  The above
example may be misleading because the entries may have been split into two
lines by the word-processor that this manual was created on.  There should
be no blank lines between each entry.

A vertical bar (|) terminates each section of each entry.  The first
section, <pattern> (the #?.LHA in the first entry of the example), tells
RTInterface how to recognize an archived file.  This string can be any
valid AmigaDOS file name/wildcard combination.

The second section, <command>, is the actual command that RTInterface will
run to decompress a file.  Wherever a percent sign (%) appears, RTInterface
will insert the file name of the compressed file.  It is a good idea to put
quotes around it in case the
file name has a space in it.  When specifying a command line to execute,
keep the following in mind:

*  It is very important to make sure that the command you specify will put
the resulting decompressed file into the Decompress directory that you
specified upon installation.  If you choose not to decompress to your
standard Decompress directory, make sure that the directory you specify is
empty, or that the contents of that directory can be deleted.  RTInterface
will automatically delete the contents of this directory before
decompression.

*  If your decompression program is not in your current path, be specific
about where it is by prepending the path to the command.

The last section, <decompress dir>, specifies the directory where
RTInterface will find the resulting decompressed file.

Also note that compressed files will should not include anything but the
MOD file.  There should be no extraneous files in the archive.  This will
change in the registered version of RTracker to be smarter about detecting
what is a MOD file and what is not.

Make sure that there are no extraneous spaces in the entries (no spaces
before or after the vertical bar, and no spaces where not needed).
RTInterface may choke if there are.
3.2  The Main Window

The control gadgets are found in RTInterface's Main Window.  When you first
boot up RTInterface, RTInterface presents you with the Main Window.

The Main Window is also an APPWindow.  Simply dumping icons from the
Workbench onto the main window will load the MOD into memory, and
optionally decompress and play the MOD.  It works the same as if you had
clicked on the Load gadget.


3.2.1  Gadgets

For the most part, you will be using RTInterface's gadgets to manipulate
the MOD in memory.  The following five sections (3.2.1.1 - 3.2.1.5) will
describe the different gadgets by their groupings (or "panels").

A note about string gadgets:  All string gadgets connect to each other.
Pressing the TAB key while in a string gadget will move the cursor to the
next string gadget.  Pressing SHIFT TAB will move the cursor to the
previous string gadget.

Slider and Scroller gadget arrows may be used to move the slider left and
right.  If you hold the arrow gadgets down for a few seconds, the they will
auto-repeat.


3.2.1.1  Control Panel

The Control Panel is located in the upper-left hand corner of the Main
Window.  It comprises of five gadgets that control the flow of music being
played.  These gadgets are (in order from upper left to bottom right):
Load, Eject, Stop, Play, and Pause.

To play a song, you must first load it into memory.  The Load gadget will
open a standard system file requester, which you may then use to select a
module to load.  The file requester will automatically positions to your
default MOD path.  Upon selecting a module, any decompression that needs to
be done will execute.  If your prefs specify to automatically play the song
after it's loaded, it will then proceed to do so.  For more information on
the system file requester, please read the manuals included with your
AmigaDOS distribution.

To remove a song from memory, and to free that memory up, you may click on
the Eject button.  Again, depending on your prefs, a file requester will
appear to prompt you for your next selection.

Hitting the Stop gadget will halt a song in mid-play.  The song will stop
playing, but will not unload from memory.  You may not continue the song
where you left off after pressing Stop in all cases except for one.  See
the Pause command for more information.  If you press Stop while within
Pause mode, Pause will be cancelled, and the player will stay in Stop
state.

The Play button serves two functions.  If you have just loaded a MOD into
memory, or Stop have recently pressed Stop, Play will start playing the
song from the beginning.  If you press Play while Pause mode is in
progress, the player will drop out of Pause mode and continue where you
Paused it.

Pause has two functions, one of which is a special case used with the Stop
gadget.  Pressing Pause while a song is playing will drop the player into
Pause mode.  All music will stop.  Pressing Pause again while in Pause mode
will cause the player to continue Play where you left off.  Earlier it was
stated that the effect of stopping a song would cause the player to start
over from the beginning.  If you decide that you would like to continue
after pressing Stop after all, double-click Pause.  This will have the
effect of continuing Play where you left off.


3.2.1.2
The Misc. Panel is located in the upper right-hand corner of the Main
Window, just under the Volume Panel.  It comprises of three checkbox
gadgets, three buttons, and one cycle gadget.  The three checkbox gadgets
are:  Help, Filter, and Loop.  The three button gadgets are:  About, Prefs,
and Refresh.  The cycle gadget is a switch between PAL and NTSC.

The first checkbox gadget, Help, causes RTInterface to go into Help mode.
To use this feature, click on the Help gadget until a checkmark appears in
it's box.  Until you click on the Help gadget again, any other gadget that
you click will open a window stating the respective gadget's functions and
how to use it.  To deactivate Help mode, simply click on the Help gadget
until the checkmark goes away.

The second checkmark gadget, Filter, toggles the Amiga's internal filter on
and off, and also the power LED.  Some older Amigas don't support this
feature.

To enable looping, activate the Loop gadget.  Looping has the effect of
starting the song over when it has played through.  If looping is not
activated, the player will go into Stop state after the song is done.

The first button, About, will open the About Window.  This displays
information about RTInterface.  For more information on the About Window,
see section 3.4.

The second button, Prefs, will open the Prefs Window.  Here, you will be
able to modify your preferences.  For more information on the Prefs Window,
see section 3.3.

If some other program sends RTracker an AREXX command, such as Stop, the
player will comply and do so without RTInterface's knowledge.  The
interface will think that RTracker is still playing.  Whenever the player
and the interface get out of sync, pressing the Refresh gadget will fix it.
A Refresh is automatically executed if some another program tells RTracker
to Load a new song.

The last gadget in the Misc. Panel is the Timing cycle gadget.  Clicking on
this gadget has the effect of switching between PAL and NTSC.


3.2.1.3  Position Panel

The Position Panel is located right under the Misc. Panel.  It is comprised
of six gadgets.  The gadgets are (in order):  Position string gadget, Fast
Rewind, Fast Forward, Slow Rewind, Slow Forward, and Position slider.

All the above mention gadgets work synchronously.

The Fast Rewind and Fast Forward gadgets will move the player one block
backward (one block is usually comprised of 63 musical events) or one block
forward, respectively.

The Slow Rewind gadget will put the player about 5 musical events earlier.

The Slow Forward gadget will increase the player speed significantly for a
few seconds - in effect, forwarding the play sequence.

If you would like to explicitly tell the player what block to jump to, you
can enter it in the Position string gadget.  Press return, TAB, or SHIFT
TAB will execute the jump.

The slider gadget manually positions the currently playing block.  The
slider gadget and the text display to the left also have an added function:
They also update to tell you where in the current MOD you are.  The slider
also auto-sizes itself to be proportionally correct in it's container.


3.2.1.4.  Volume Panel

At the top of the Main Window is the Volume Panel, directly below the MainWindow title bar.  It is comprised of one standard scroller gadget and
string gadget.

Moving the scroller gadget left and right will modify your MOD's volume.
Moving the slider to the left will decrease the volume, while moving it the
opposite way does the exact opposite.  To the left of that gadget is the a
string gadget where you can specifically specify the volume.  Valid volume
values (hey - is that a tongue twister or what?) range from 0 to 63, 63
being the loudest.


3.2.1.5  Tempo Panel

The Tempo Panel is located at the very bottom of the Main Window.  It is
comprised of two scrollers and their respective string gadgets.

The Coarse Tempo scroller allows you to change the tempo of the current
MOD.  This slider actually changes the delay value between events.  A value
of zero (the middle of the slider) specifies the normal tempo, which is
either standard PAL or standard NTSC, depending on what you have it set to.
The more negative your value is, the faster the mod will go.  The converse
is also true.  Valid values for the string gadget range from -16 to 15, -16
being the fastest, 15 being the slowest.

The Fine Tempo scroller is the same as the Coarse Tempo scroller except
that it is used to fine-tune the current Coarse Tempo.  Valid values for
the string gadget range from -128 to 127.  A value of zero specifies the
exact Coarse Tempo setting.


3.2.2  Menus

There are three separate menus:  Project, Settings, and Control.  They are
an alternative method of operating the interface, and also provide for
command keys.  Command keys are a keyboard short-cut method of operating
the interface.  See your Amiga manual for more information on command keys.


3.2.2.1  Project Menu

The Project Menu is located in the left-most corner of the menu strip.  It
is comprised of five menu items:  Load, Eject, Prefs, About, and Quit.

The Load, Eject, Prefs, and About menu items are exactly equivalent to
their respective gadgets on the Main Window.  For more information on Load
and Eject, see section 3.2.1.1.  For more information in Prefs and About,
see section 3.2.1.2.

The Quit gadget is equivalent to hitting the close box in the upper right
hand corner of the Main Window.  It has the effect of exiting the program,
and possibly executing the RTQuit.script script file.


3.2.2.2  Settings Menu

The Settings Menu is located in the middle of the menu strip.  It is
comprised of four menu items:  PAL, Filter, Loop, and Help.

All four items are toggle items.  Filter, Loop, and Help have the same
functions as their gadget equivalents in the Main Window.  The PAL
functions the same as the PAL/NTSC cycle gadget in the Main Window.  For
more information on these functions, see section 3.2.1.2.  These menu items
are connected to their respective gadgets.  Changing the state of the menu
or the gadget will also modify the object's significant other.


3.2.2.3  Control Menu

The Control Menu is located to the right of all the menus in the menu
strip.  It is comprised of three menu items:  Stop, Play, and Pause.
All three items are exactly equivalent to the gadgets in the Control Panel
with the same name.  For more information on these functions, see section
3.2.1.1.


3.3  The Prefs Window

The Prefs Window is accessible from the Main Window's Misc. Panel.  It
contains seven different panels.  The panels are:  Defaults, F/X, Timing,
Bootup, Default MOD Path, Port, and Confirm.  Using these panels, you can
set RTInterface to function the way you want it to.

All the options in the Prefs Window have an equivalent in the RTPrefs file.
For more information on RTPrefs, see section 3.1.3.


3.3.1  Gadgets

The following seven sections (3.3.1.1 - 3.3.1.7) will describe the
different gadgets by their groupings (or "panels").

A note about string gadgets:  All string gadgets connect to each other.
Pressing the TAB key while in a string gadget will move the cursor to the
next string gadget.  Pressing SHIFT TAB will move the cursor to the
previous string gadget.


3.3.1.1  Defaults Panel

The Defaults Panel is located in the upper left corner of the Prefs Window.
It is comprised of four checkbox gadgets.  Using these gadgets, you can
specify how RTInterface will operate.

The AutoPlay option allows you to specify whether or not the player will
automatically play the MOD right after loading and decompressing.

The Decompress option specifies whether RTInterface will attempt to
decompress an archived file when it encounters one.

The AutoDetect PAL/NTSC option specifies whether or not RTracker will try
to load timing information from a MOD.  Unless you have MODs with this
embedded information in them, this should be turned off.  When this
function is on, the Timing prefs located in the Timing Panel will have no
effect.

If you would like the interface to prompt you for a MOD after an Eject,
activate the Request on Eject function.


3.3.1.2  F/X Panel

The F/X Panel is located in the upper portion of the Prefs Window in the
center.  It is comprised of two checkbox gadgets:  Filter and Loop.  The
F/X Panel will allow you to set the defaults pertaining to different
audible effects.

If Filter is active, the filter will turn on every time a new MOD loads.

If Loop is activated, the loop checkbox on the Main Window will be
automatically activated upon loading a new MOD.


3.3.1.3  Timing Panel

The Timing Panel is located in the upper right corner of the Prefs Window.
It is comprised of one set of mutually exclusive gadgets.  Selecting one or
the other will affect the PAL/NTSC cycle gadget in the Main Window.  The
PAL/NTSC cycle gadget will be set to the selection in this panel whenever a
new MOD loads into memory.  Note that this function is disabled if
AutoDetect PAL/NTSC is activated in the Defaults Panel.  For more
information on the PAL/NTSC cycle gadget, see section 3.2.1.2.  For more
information on the AutoDetect PAL/NTSC option in the Defaults menus, seesection 3.3.1.1.


3.3.1.4  Bootup Panel

The Bootup Panel is located in the middle of the Prefs Window.  It is
comprise of three checkbox gadgets, one string gadget, and a directory
requester gadget.  The three checkbox gadgets are:  AutoLoad, AutoUnload,
and AutoRequest.  The string gadget is the RTracker Directory gadget.  The
Bootup Panel is used to set the defaults dealing with bootup.

If the AutoLoad checkbox gadget is activated, the RTLoad.script file will
execute upon bootup of RTInterface.  For more information on RTLoad.script,
see section 3.1.1.

If the AutoUnload checkbox gadget is activated, the RTQuit.script file will
execute upon shutdown of RTInterface.  For more information on
RTQuit.script, see section 3.1.2.

The RTracker Directory string gadget must contain the path where RTracker,
RTracker's modules, and RTInterface's support files are kept.  Otherwise,
RTInterface won't be able to find anything.  The directory gadget to the
right of the string gadget will bring up a requester to let you choose a
directory automatically.  Your selection will be inserted into the RTracker
Directory string gadget.


3.3.1.5  Default MOD Path Panel

The Default MOD Path Panel is located directly under the Bootup Panel in
the Prefs Window.  It contains only two gadgets.

The string gadget in this panel is used to store your default MOD Path.
RTInterface will default to this path when asking for a MOD.  The file
requester gadget to the right will insert your selection into the string
requester.


3.3.1.6  Port Panel

The Port Panel is currently unused.  Leave it alone, and don't bother it.
It doesn't like to be disturbed.  Warning:  If you play with this string
gadget and it physically hurts you, it is not my fault.  I warned you.


3.3.1.7  Confirm Panel

The Confirm Panel is at the bottom of the Prefs Window.  It is not
labelled.  There are three gadgets in this panel.

The first gadget, Help, causes RTInterface to go into Help mode.  To use
this feature, click on the Help gadget until a checkmark appears in it's
box.  Until you click on the Help gadget again, any other gadget that you
click will open a window stating the respective gadget's functions and how
to use it.  To deactivate Help mode, simply click on the Help gadget until
the checkmark goes away.

The last two buttons, Cancel and Okay should be self explanatory.  Cancel
will abort any changes to your preferences and exit the preferences editor.
Clicking on Okay will modify your prefs, and modify the RTPrefs file to
reflect the changes.  For more information on RTPrefs, see section 3.1.3.


3.3.2  Menus

There is only one menu in the Prefs Window, the Prefs Menu.  The entries
are:  OK, Help, and Cancel.  These functions are equivalent to their
Confirm Panel counterparts.  See section 3.3.1.7 for more information on
these menu items.

3.4  The About Window
The About Window is a small window that displays various pieces of
information.


3.4.1  Gadgets

The only gadget in the About Window is the OK Gadget.  Clicking on this or
the off gadget will exit the About Window.


3.4.2  Menus

Whatever you do, don't tickle it.


3.5  AREXX Commands

RTInterface supports a few different AREXX commands.  For the most part,
the average user will not have to use them.

RTInterface's AREXX Port is "RTracker", case sensitive.

The AREXX commands follow.  They are all case sensitive.

'quit' - quits RTInterface

'tick' - used primarily by RTracker.  This tells RTInterface to refresh
it's position slider gadget.  For more information on the position slider
gadget, see section 3.2.1.3.

'refresh' - used primarily by RTracker.  This tells RTInterface to do the
equivalent of pressing the Refresh gadget.  For more information on the
Refresh gadget, see section 3.2.1.2.


4  The Player

The Player, RTracker, is the heart of the whole system.  It contains all
the code to do effects, and so forth.  Although it has no interface, it has
a good size command set which is growing every day.  The next section will
document those AREXX commands.

When run, RTracker will open a small window.  It will always display it's
current status in this window.


4.1  AREXX Commands

RTracker's command set contains many synonym commands that attempt to make
it compatible with Ed Mackey's EDPLAYER, and RTracker 1.0.

<n>  denotes an optional argument
<<n>> denotes a required argument

'goodbye', 'quit', 'kill'
Tells RTracker to clean up and die.

'playsong', 'play' <n>
Tells RTracker to play the currently loaded MOD.  It takes one optional
parameter, a file name.  If you supply a MOD's file name, that MOD will
load first.

'contsong', 'cont'
Continue play from where you last left off.

'stopsong', 'stop', 'paus'
Stops the current play sequence.

'changetempo', 'tempo' <n>
Changes the current coarse tempo setting.  Valid values are -16 to 15, zero
being the base speed (either NTSC or PAL, depending on which you haveset as the base speed).  The smaller the number, the faster the tempo.

'about' - Displays some version info in the RTracker window.

'autodetect' <n> - Turns MOD timing automatic detection on or off.  See the
Auto Detect PAL/NTSC subsection in section 3.1.3 for more information on
this feature.

'changeftempo', 'ftempo' <n> - Same as 'changetempo' and 'tempo', but with
the difference that this sets fine tempo.  The base speed is the current
Coarse tempo.  Valid values are -128 to 127, zero being the base value.

'dvolume', 'dvolu' <<n>> - Change the volume relative from the current
volume.  If you specify a value too big or too small, RTracker will catch
it and use a value that will stay within the proper bounds.

'fadedelay' <<n>> - Set the fade delay value.  The path is required.  Fade
values can range from 0 to 31, inclusive, 0 being very fast, 31 being very
slow.

'fadedown' <n> - Fades the song down from the current volume regardless of
whether or not Fade Mode is on.  After it's done, it will set Fade Mode
off.  The optional argument is the fade delay rate.  See the 'fadedelay'
command for information on the delay rate.

'fadeoff' - Turns Fade Mode off.

'fadeon' - Turns Fade Mode on.  If this is activated, sending Stop or Play
to RTracker will fade the song volume down or up, respectively.

'fadeup' <n> - Fades the song up from zero volume regardless of whether or
not Fade Mode is on.  After it's done, it will set Fade Mode off.  The
optional argument is the fade delay rate.  See the 'fadedelay' command for
information on the delay rate.

'fblock' - Jump forward one block.

'filter' <n> - A value of 1 will activate the Amiga's built in sound
filter.  A value of zero will turn it off.

'jump' <<n>> - Jumps to block <<n>> in a MOD.

'loadsong', 'load' <<n>> - Loads a new MOD from disk.  The parameter is
required to load a MOD.

'menu', 'front' <n> - If the argument is non-zero, RTracker's window will
come to the front.  If the argument is zero, RTracker's window will move to
the back.

'rblock' - Jump backward one block.

'repeat' <n> - Repeat will play the MOD <n> times before stopping.  A value
of zero tells RTracker to continually repeat.

'repend' <n> - A value of 1 will turn repend on.  A value of 0 will turn
repend off.  If repend is activated, when the song finishes playing, the
player will jump back a block, and replay it while fading the song.

'restorevol' - If you've messed up the volume by fading and so forth,
restorevol will fix it.

'rline' - Jump backward a few events.

'scarce', 'eject' - Unloads the currently loaded MOD.

'self' <n> - Short for self destruct.  Sending this to the RTracker will
immediately fade the song and then kill RTracker.  The optional argument is
the fade delay rate.  See the 'fadedelay' command for information on the
delay rate.

'timing' <n> - Sets the base timing of the MOD.  A value of 0 denotes NTSC,
a value of 1 denotes PAL.
'volume', 'volu' <<n>> - Changes the volume.  Valid values range from 0 to
63, 63 being the loudest.


5  The Libraries

RTracker and RTInterface use two libraries for some of its functions.
RTracker uses DesTracker.Library, and RTInterface uses both
DesTracker.Library and RexxHost.Library.


5.1  DESTracker

The DesTracker library is what RTracker uses to play MODs.  Throughout the
development of RTracker, I've used many different methods of handling
module data.  Version 1.0 of RTracker didn't even support SoundTracker type
files; only MED files.  This didn't sit well with me, so I then moved on
and implemented my own in assembly language.  I didn't like that either.
After months of searching for MOD format information, I finally found an
ideal choice.  That choice was Darren Schebek's DesTracker library.
Because DesTracker is a library, it can easily be replaced to support more
MOD, or even MED formats (are you listening, Darren? ;).

It is also very compatible with the new Amiga operating system(s).


5.2  RexxHost

The RexxHost library is what RTInterface uses to implement an AREXX port.
Before I got this library, the AREXX port was implemented using the minrexx
distribution.  RTracker uses minrexx, while RTInterface uses the
RexxHost.library.  They are both very good, and very compatible; I'm not
sure yet which one I like better.  RexxHost does, however, have a definite
advantage:  it's a shared library.  Most likely, RTracker will be
re-written to use the RexxHost library.


6  Credits

I'd like to take this change to thank my beta testers, and all the people
who have given me their opinions and critiques of the program.  Their names
follow.

The C-SIG gang -
    Charlie Johnson
    Forrest Towne
    Ed Musgrove
    Adolf Weindanz

My official RTracker BBS support board sysops:
    Jim Lynch
    Keith Thibodeaux
    Larry Cloud

The library authors:
    Darren Schebek
    Olaf Barthel

And the following people for their ideas and input that had a direct impact
on this revision:
    Trev Dagley
    Matt Splett
    David Radke
    Nick Salvatico
    Michael Mac Ness
    Daniel Lehenbauer

I'd also like to thank Commodore for an excellent machine.  I hope in the
future that I can say the same about Commodore ;).

7  The Future

Hopefully, RTracker will grow and become the best MOD Player out on the
market.  I can't promise that it will be, but I can certainly guarantee
that if you keep those comments rolling in, I will make it a priority to
incorporate your idea of perfection into a future revision.

Future improvements to the current software that will possibly make it into
the next SHAREWARE release (and guaranteed to be in the registered
version):

*  Smooth fade on the last block of a MOD.

*  Double buffering

*  More support for different types of modules.

*  Selection of MODs within an archive without having to decompress the
whole thing.

*  Support for fading in RTInterface.

*  Iconification of RTInterface into an APPIcon.

*  Making RTracker into an APPWindow.

Future RTracker modules to be released are:

RTMultiPlayer - a fully programmable multi-MOD loader and player,
supporting fades and so forth, and a scripting language or a GUI interface
with options for programmed or random play.  Possibly double buffering of
MODs.  Some suggested features are:

*  CLI arguments, like REPEAT (=# of times, default is always repeat)

*  Saying which device/directory your mods are in and then loading them up.

*  Fading selectable on EACH MOD individually.

*  List saving

*  Fade out/no fade out status saved in script.

*  Batch selection of MODS

*  Ability to output the currect selection to a file you can read upon
startup each time, so you won't have to re-select all 100+ files.

*  The ability to just give it a directory path, and tell it to load all
files.

RTIcon - a small Interface module that opens an APPIcon that you can dump
MODs into.

RTEffects - a module to do special effects with modules.  Don't know about
this one.  Opinions?  Comments?  Blah?


8  Index

<command>  8
<decompress dir>  8
<path>  5-7
<pattern>  8
AREXX  1, 3, 5-6, 10, 14, 16
AREXX Commands  1, 14
arrows  9
at-sign  8
Auto Detect PAL/NTSC  7, 15
Auto Detect PAL/NTSC   7, 15
Auto Load  7
Auto Play  7
Auto UnLoad  7
block  10, 15, 17
Bootup Panel  1, 13
Cancel  13
Coarse Tempo  11, 14-15
Comments  5, 8, 17
Confirm Panel  1, 13
Contents  1, 8
Control  1, 3, 9, 11-12
Control Menu  1, 11
Control Panel  1, 9, 12
Copyright  1-2
Credits  1, 16
Decompress  1, 3-5, 7-9, 12, 17
Decompress directory  8
Decompress.RTPrefs  1, 4-5, 8
decompression  3-4, 7-9
Default MOD Path Panel  1, 13
Defaults Panel  1, 12
DESTracker  1-2, 4, 7, 16
DESTracker.Library  2, 4, 16
Disclaimer  1, 17
DTC  7
EDPlayer  3, 14
F/X Panel  1, 12
Fade Mode  15
Filter  7, 10-12, 15
Fine Tempo  11, 15
Forward  10, 15
Gadgets  1, 9-14
Help  4, 10-11, 13
Installation  1, 4, 8
Installer  4, 8
Introduction  1, 4
LHa  4, 8
Libraries  1, 4, 16
LIBS:  4
Load  5, 7, 9-12, 14-15, 17
Main Window  1, 9-12
Menus  1, 11, 13-14
Misc. Panel  1, 10, 12
MOD  1, 3-4, 7-17
MOD path  1, 4, 7, 9, 12-13
NIL:  6
NTSC/PAL default switch  7
Okay  13
panels  9, 12
player  1, 3-5, 7, 9-10, 12, 14-15, 17
Port Panel  1, 13
Position Panel  1, 10
PowerPacker  4
Preface  1, 3
Prefs Menu  13
PREFS:  4, 8
Project  1, 11
Project Menu  1, 11
Repeat at end  7
Request on Bootup  7Request on Eject  7, 12
Rewind  10
RexxHost  1-2, 4, 16
RexxHost.library  2, 4, 16
RTInterface  2-10, 12-14, 16-17
RTLoad.script  1, 5-7, 13
RTPrefs  1, 4-6, 8, 12-13
RTQuit.script  1, 5-7, 11, 13
RTracker  2-8, 10, 12-17
RTracker path  5, 7
Scope  2
Scroller  9, 11
Settings  1, 5, 11
Settings Menu  1, 11
Slider  9-11, 14
Slow Forward  10
Slow Rewind  10
spectrum analyzer  2-3
Tempo Panel  1, 11
The About Window  1, 10, 14
The Future  1, 16-17
The Install Program  1, 4
The Interface  1, 3, 5, 10-12
The Libraries  1, 4
The Main Window  1, 9-12
The Player  1, 5, 7, 9-10, 12, 14-15
The Prefs Window  1, 10, 12-13
The Script Files  1, 5, 8
Timing Panel  1, 12
User-Startup  4
vertical bar  8
Volume Panel  1, 10-11
VU meters  2-3
9  Disclaimer

Boy, do I hate these things.  I'll make it short.

If this software totally screws up your system, it's not my fault.  Use at
your own risk.  I'm not, of course, saying that it will.  Just... in case?